Type hints

Iterating to incrementally add type hints to submodules,
based on works done in these PRs:
#1262
#1263
#1264
#1265
#1266

Strategy

• Start with small functions/classes and functions/classes that require few external dependencies.
• Moving gradually one function by one function, in the four test suites: starting from "core", then "compact", then "extra", and "noauto".

Goals

• Immediate goal for this session - 100% type hints for functions/classes being called in "extra" test suite.
• Ultimate goal (outside of this session) is to reach 100% type hints in the entire repo, make the package a typed package, while keeping maintainability.

Instructions

• Follow best practices and standard Python type hint patterns.
• Start small in the area with high confidence (like highly tested submodules or functions), then gradually grow one submodule at a time.
• Use mypy as main assistant.
  • mypy is already in "dev" extra dependencies in pyproject.toml
  • mypy configuration is in pyproject.toml
  • Sometimes mypy may report errors wrongly due to cache issues. Try to reset the cache.
• Use pyright, pyrefly, and pytype for second opinions.
• Required dependencies for each test suite are in pyproject.toml. Install them to avoid errors. See https://github.com/PyThaiNLP/pythainlp/blob/dev/tests/README.md
• Use native type in type hint (list, tuple, .. instead of List, Tuple, ..)
• Do not use A | B style Union, use full Union[] instead.
• We want to keep compatibility with Python 3.9 strict and allow type inspection tools to work correctly.
• When insert typing imports, put it in appropriate location and order
• Use "if TYPE_CHECKING import" block when possible.
• When reordering the imports, beware of circular import. Read comments near imports to get more information.
• Remove unused imports
• Do not allow the use of assert in production code (it is only allowed for testing and debugging).
• Try to fix the type, the scope logic, or do the casting, before putting #type: ignore comment.
• When dealing with types from external libraries:
  • Check if type information is provided (maybe through stubs). If it is, cast wrapper may not necessary.
  • If return type is not provided, may be it is appropriate to use # type: ignore[no-any-return] annotation for clarity.
• Recheck necessity when do casting.
• Recheck necessity of # noqa: and # type: ignore
• Provide type stubs as necessary.
• After changes for type hints, recheck for functionality correctness.
• Recheck docstring and documentation consistency with the code; They should match the updated type hints.
• Recheck formatting with ruff
• Do another code review
• Address code review feedback